Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / UTILITY / XSPAWN.ARJ / MANUAL.DOC < prev next >

Wrap

Text File | 1991-05-04 | 18KB | 396 lines

XSPAWN Version 1.33 (C) Copyright 1990 Whitney Software, Inc. All Rights Reserved Microsoft and MS-DOS are registered trademarks of Microsoft Corporation. Turbo C is a registered trademark and VROOMM is a trademark of Borland International. Lattice is a registered trademark of Lattice, Incorporated. XSPAWN 1 _____________________________________________________________________ Overview The XSPAWN functions allow you to run a large program on top of another program by swapping the underlying program to EMS memory or to disk. This frees most of the DOS memory occupied by the underlying program (both code and data segments) and returns it to DOS for use by other programs or a DOS shell. The "parent" program is automatically restored upon completion of the "child" program and execution resumes where the parent program left off. The XSPAWN functions can be called over and over again from one program to another. System Requirements XSPAWN supports DOS versions 2.1 and later. Programs using the XSPAWN functions instead of the standard C run-time library spawn functions (fork functions in Lattice C) require up to 9K additional DOS memory (4K on average). XSPAWN requires sufficient EMS (3.2+) memory or sufficient disk space to perform a swap. XSPAWN Kernel The XSPAWN code that remains in memory while the child program is executing is called the "XSPAWN kernel." The XSPAWN kernel is 1021 bytes in size. In addition to the XSPAWN kernel, the parent program's environment, the parent program's PSP (program segment prefix), and the environment to be passed to the child program remain in memory while the child program is executing. The program segment prefix is 256 bytes in size. Compilers and Memory Models Supported XSPAWN supports all standard memory models for Microsoft C (4.0, 5.0, 5.1, and 6.0), Turbo C++ (1.0), Turbo C (2.0), and Lattice C (6.0). XSPAWN supports Turbo C++'s VROOMM overlay manager (as long as XSPAWN is in the overlaid application's base). XSPAWN 2 _____________________________________________________________________ Using the XSPAWN Functions To use the XSPAWN functions you must include the XSPAWN.H header file in your program, call the XSPAWN function that is equivalent to the standard C run-time library spawn function (fork function in Lattice C) you wish to use, and link with the appropriate XSPAWN library. The XSPAWN functions have the same name as their standard C counterparts (for Lattice C change fork to spawn) with the letter x prefixed. The XSPAWN functions expect the same arguments as their standard C counterparts (the modeflag argument does not exist in Lattice C fork functions). The XSPAWN family consists of the following functions: int xspawnl( modeflag, path, arg0, arg1..., argn, NULL ); int xspawnle( modeflag, path, arg0, arg1..., argn, NULL, envp ); int xspawnlp( modeflag, path, arg0, arg1..., argn, NULL ); int xspawnlpe( modeflag, path, arg0, arg1..., argn, NULL, envp ); int xspawnv( modeflag, path, argv ); int xspawnve( modeflag, path, argv, envp ); int xspawnvp( modeflag, path, argv ); int xspawnvpe( modeflag, path, argv, envp ); int modeflag; Execution mode for parent process char *path; File to be executed char *arg0, *arg1..., *argn; List of pointers to arguments char *argv[]; Array of pointers to arguments char *envp[]; Array of pointers to environment strings int xsystem( command ); char *command; Command to be passed to COMMAND.COM The modeflag argument must be P_WAIT. The modeflag argument exists only for compatibility with the standard C spawn functions. (The modeflag argument does not exist in Lattice C fork functions.) The parent process will be suspended while the child process is executing. XSPAWN 3 _____________________________________________________________________ The path argument specifies the file to be executed. The path can be just a file name or it can be a full or partial path (from the current working directory). If path does not have a filename extension or end with a period, XSPAWN will try the extension .COM and then, if necessary, the extension .EXE. The xspawnlp, xspawnlpe, xspawnvp, and xspawnvpe functions search for path in the directories specified by the PATH environment variable. Arguments are passed to the child process by giving one or more pointers to character strings as arguments in the XSPAWN call. The combined length of the strings (not including the first string, but including space characters inserted automatically for separation) may not exceed 124 bytes. The strings can be passed as separate arguments (xspawnl, xspawnle, xspawnlp, and xspawnlpe) or as an array of pointers (xspawnv, xspawnve, xspawnvp, and xspawnvpe). At least one argument must be passed to the child process. The first argument is, by convention, a copy of the path argument. (Using a different value won't produce an error.) The end of the argument list must be marked with a null pointer. Files that are open in the parent process remain open in the child process. With the xspawnl, xspawnlp, xspawnv, and xspawnvp functions, the child process inherits the parent's environment. With the xspawnle, xspawnlpe, xspawnve, and xspawnvpe functions, the child process acquires the environment passed through the envp argument. The envp argument is an array of pointers to character strings where each string defines an environment variable. Each string is of the form variable=value where variable is an environment variable and value is its string value. The final element of the array must be NULL. When envp is NULL, the child process inherits the parent's environment. The xsystem function passes command to the file COMMAND.COM for execution. The COMSPEC and if necessary PATH environment variables are used to locate the file COMMAND.COM. If command is NULL and if the function locates COMMAND.COM, it returns 1. If it does not locate COMMAND.COM, it returns 0 and sets errno to ENOENT. If the child process is started, the return value is the exit status of the child process. The return value will be 0 unless either the child process called the exit function with a nonzero argument or the child process exited abnormally with an abort call or an interrupt. XSPAWN 4 _____________________________________________________________________ If the child process is not started, the XSPAWN functions return -1 and set errno to one of the following values: Value Meaning --------------------------------------------------------------------- E2BIG The argument list exceeds 124 bytes or the environment is not less than 32K. EACCES Access to the swap file was denied, no handle was available for the swap file, the file handle table size did not equal FHTSZ in the file XSPAWN.ASM, attempt to map EMS memory failed, or attempt to restore EMS memory page-mapping state failed. There may be insufficient EMS (3.2+) memory and disk space on the specified paths. EINVAL The modeflag argument is not P_WAIT. ENOENT The specified file was not found. ENOEXEC The specified file is not executable. ENOMEM Not enough memory is available to execute the child process or the memory control blocks are corrupted. Controlling the Swap Operation There are four global variables defined in XSPAWN.H which allow you to control the swap operation of all of the XSPAWN functions. The XSPAWN global variables and their actions are as follows: _swap If _swap is 0 (the default), XSPAWN will attempt to swap out the parent process before executing the child process. Any other value, and XSPAWN will execute the child process without swapping out the parent process. In other words, if _swap is not 0, XSPAWN will behave like the standard C run-time library spawn functions (fork functions in Lattice C). XSPAWN 5 _____________________________________________________________________ _swappath If _swappath is a null pointer (the default), XSPAWN will attempt to write the swap file (if EMS memory is not used) to the current directory on the current drive. You can specify one or more alternate paths for the swap file by assigning a string to _swappath as follows: _swappath = "D:\\;C:\\SCRATCH"; Each separate path specifier in the _swappath string (separated by a ;) can contain a drive, a directory, or both. If you do not specify a drive, XSPAWN will use the current drive. If the directory is not specified, XSPAWN will use the directory that is current on the target drive. You may be wondering why you would ever want to specify multiple paths. To illustrate one use of this feature, let us say your system has a ramdrive called D: and a hard drive called C:. Since writing to a ramdrive is many times faster than writing to a hard drive, you would naturally prefer to write the swap file to the ramdrive. The problem is that there may not be enough space on the ramdrive to hold the swap file. The _swappath string shown above would cause XSPAWN to try the ramdrive first and if there is insufficient space, to try the C: drive next. If a path does not exist, XSPAWN will skip it. If XSPAWN can't store the swap file on any of the specified paths, it will return -1 and set errno to EACCES. _useems If _useems is 0 (the default), XSPAWN will check for the existence of EMS (3.2+) memory and if there is enough EMS memory, will swap the parent process there instead of to disk. You can disable the use of EMS memory by assigning a nonzero value to _useems. _required If you know the amount of memory required by the child process, you can assign the amount in kilobytes to _required. Regardless of the value of the _swap variable, if _required is less than or equal to the amount of memory that is already free (without swapping out the parent process), XSPAWN will execute the child process without swapping out the parent process. If _required is 0 (the default) and _swap is 0, XSPAWN will attempt to swap out the parent process. XSPAWN 6 _____________________________________________________________________ Linking XSPAWN Into Your Program The XSPAWN functions can be linked into your program by including the XSPAWN library appropriate for your compiler and memory model on your linker command line. Interrupt Handlers Something must be done with captured interrupt vectors that point to interrupt handlers in your program. This is true for two reasons. First, if XSPAWN swaps out your program, the interrupt handlers in your program will no longer be in memory. Second, even if XSPAWN doesn't swap out your program, it is probably undesirable to have interrupt handlers in your program invoked in response to interrupts that occur while the child process is executing. If you capture interrupts, you should read the following to understand how XSPAWN handles interrupts. Before executing the child process, XSPAWN saves the current content of the vectors listed in a XSPAWN table called the "vector table" and replaces the content of these vectors with addresses stored in the table. After executing the child process, XSPAWN restores the vectors that were saved. By default, the vector table contains the interrupts: 0, 1, 2, 3, 1BH, and 23H. Associated with the default interrupts is the address of an interrupt handler in the XSPAWN kernel (the XSPAWN code that remains in memory while the child process is executing) that consists of only an IRET (INTERRUPT RETURN) instruction. By default, the default interrupts will do nothing if invoked while the child process is executing. You can add or change entries in the vector table by using the addvect function. int addvect( number, opcode ); int number; Interrupt number int opcode; Operation code The number argument must be an integer from 0 to FFH. The opcode argument can be either IRET or CURRENT. If the value is IRET, the interrupt will point (while the child process is executing) to the interrupt handler in the XSPAWN kernel that consists of only an IRET instruction, unless the child process captures the interrupt. If the value is CURRENT, the interrupt will point to the interrupt handler that is in effect when the addvect function is called. XSPAWN 7 _____________________________________________________________________ If the addvect function fails, it returns -1 and sets errno to one of the following values: Value Meaning --------------------------------------------------------------------- EINVAL The opcode argument must be IRET or CURRENT. ENOMEM The vector table is full. The vector table has space for 20 entries (6 are used by default). If more entries are desired, you will have to modify and compile the file XSPAWNVE.C. Add free records to the vectab1 array. No other changes are necessary. It is typical to call addvect with an opcode of CURRENT before you capture an interrupt. This will cause XSPAWN to set the interrupt to its original value while the child process is executing. To find out what interrupt vectors are captured by your program, use an XSPAWN function other than xsystem (with the _swap variable set to a nonzero value) to run MP.COM from your program. Remember by default, XSPAWN captures the interrupts: 0, 1, 2, 3, 1BH, and 23H. Interrupt 22H will point to your program because DOS uses it to store the return address from the child process. File Handle Table Size If you have increased the file handle table size so that more than 20 files may be open in the parent process, you will have to modify and assemble the file XSPAWN.ASM. Change the line FHTSZ EQU 20 so that FHTSZ is set to the new size. To increase the file handle table size for Microsoft C versions 5.0, 5.1, or 6.0, see the description of the necessary modifications to the startup code in the README file accompanying the compiler. XSPAWN 8 _____________________________________________________________________ Fatal Errors If XSPAWN is unable to restore the parent process upon completion of the child process, it will display the message "XSPAWN error" and exit to DOS with an exit status of 1. This can occur for several reasons: 1. The child process may have made itself permanently resident. 2. The swap file may have been erased or corrupted. 3. There may have occurred a disk read error. 4. There may have occurred an EMS memory management error.